===============================================================================

                  OPTIMIZATION STACK  -  PORTABLE BUNDLE

===============================================================================


  Mod stack created, curated, and tuned by zebyve.

  The individual mods are the work of their respective authors, each credited
  by name below. zebyve assembled this selection, dialed in the configuration,
  and tuned it to the results described here.


-------------------------------------------------------------------------------


A drop-in optimization layer for Forge 1.20.1, originally built for the
"Dreaded Void" pack.

On an integrated / peer-to-peer server running 36 dimensions, this stack took
performance from 3-5 TPS up to a steady 20 TPS with zero "Can't keep up"
warnings.

Most of this stack is focused on the SERVER THREAD and MEMORY and does not
touch mob behavior at all. Two mods are the exception: Does It Tick? and No
See No Tick suspend entity ticking by distance, which DOES change AI behavior
for anything they freeze. On horror or boss-heavy packs, read
"READ IF MAKING HORROR MODS.txt" before playing - it is a one-line whitelist
fix, not a reason to drop them.




===============================================================================

  1.  READ THIS FIRST  -  WHAT IS ACTUALLY IN THIS FOLDER

===============================================================================


This bundle came from a CurseForge modpack export. That means the mod .jar
files are NOT included here. CurseForge stores them on its own servers and
references them by project ID.

What you have in this folder is:


  config/
      Every tuned optimization config file. This is the valuable part: the
      exact settings that produced 20 TPS, already dialed in.


  MODS-TO-INSTALL.txt
      The precise shopping list (exact names + authors) so you can add the
      matching jars from the CurseForge app or from Modrinth.


  README.txt
      This file. What each mod does and which settings matter.


To reuse the stack: install the mods from the shopping list into your target
pack, then drop this config/ folder into that pack's config/ directory,
overwriting when asked.




===============================================================================

  2.  FORGE / RAM BASELINE

===============================================================================


  Loader
      Forge 1.20.1 (tested on 47.4.10)


  RAM
      7 GB allocated is plenty and leaves large headroom. Measured peak on the
      reference pack stays under 3 GB, because FerriteCore, Saturn, ModernFix
      and Canary between them strip a great deal of memory use. Do NOT
      over-allocate; a larger heap only makes garbage-collection pauses longer.




===============================================================================

  3.  THE MODS, BY WHAT THEY DO

===============================================================================



  ---  SERVER THREAD / TICK OPTIMIZATION  (the heavy lifters)  ---


  ServerCore  (Wesley8081)

      The single most important mod here. Dynamically scales view distance,
      chunk-tick distance, and mobcap based on live MSPT, and disables the
      permanently-loaded spawn chunks across every dimension. On a 36-dimension
      world this one mod did the bulk of the work.


  ModernFix  (embeddedt)

      Broad startup and runtime patches, dynamic resource loading, and it
      catches other mods' thread-safety mistakes before they can crash you.


  Saturn  (AbdElAziz333)

      Memory allocation and GC heap reduction. This is what tipped the pack
      from "one warning per session" to zero. Removes the micro-stalls caused
      by garbage collection.


  FerriteCore  (malte0811)

      Shrinks the blockstate memory footprint. A pure win, no config needed.


  No See, No Tick  (Askaban)

      Stops entities from ticking when far from players. The TICK half is
      multiplayer only - it activates at 2+ players (minPlayers), so on a
      singleplayer world it does nothing.

      Its RENDER half is a separate matter and runs at any player count. See
      "READ IF MAKING HORROR MODS.txt" section 3; the distances in this bundle
      are already set high enough that it cannot hide anything you can see.


  Does It Tick?  (Txni)

      Companion entity-tick optimizer with a per-entity whitelist for things
      that must always tick, such as bosses.


  Chunk Activity Tracker  (Txni)

      Supplies the activity data the other Txni mods rely on.


  Clumps  (Jaredlll08)

      Merges nearby XP orbs into a single entity, cutting the entity count
      after combat or grinding. No config file.



  ---  CHUNK LOADING / SAVING  ---


  Chunky  (pop4959)

      Pregenerate terrain BEFORE sessions so the server is not generating
      chunks on the fly. This eliminated the largest exploration lag spikes.


  Server Performance - Smooth Chunk Save  (someaddon)

      Spreads chunk saves out so autosaves do not freeze the server thread.


  Fastload  (StockiesLad)

      Faster world load and join times.


  Smooth Boot - Reloaded  (AbdElAziz333)

      Rebalances thread priority during startup so loading does not peg every
      CPU core.



  ---  RENDERING / CLIENT FPS  ---


  Embeddium  (FiniteReality)

      The Sodium-equivalent renderer for Forge, and the core of client-side
      FPS. It uses Sodium's internal class names; that is expected because it
      is a fork.


  ImmediatelyFast  (RaphiMC)

      Speeds up immediate-mode rendering: text, GUIs, and item models.


  Better Fps - Render Distance  (someaddon)

      Reduces detail on distant chunks within view distance.


  Entity Culling  (tr7zw)

      Skips rendering of entities occluded by blocks or terrain, and skips
      their CLIENT-side tick (animation only). Strong FPS gain, safe on every
      pack including horror.

      Earlier revisions of this bundle told you to disable it on horror packs.
      That was incorrect and has been retracted - it culls by occlusion
      raytrace rather than distance, and it never mixins into server-side AI.
      See "READ IF MAKING HORROR MODS.txt" section 1.


  Oculus  (Asek3)

      Shader loader. Only needed if you run shaders; pairs with Embeddium.
      Optional - remove it if the target pack has no shaders.


  Sodium/Embeddium Dynamic Lights  (Txni)

      Held and dropped light sources emit light. This is immersion, not
      performance, and is safe to drop. Note: it logs a harmless class-path
      warning under Embeddium.



  ---  LIBRARIES  (required by the above; install but do not configure)  ---


  Balm  (BlayTheNinth)

      Abstraction layer; prevents conflicts if more mods are added later.


  TxniLib  (Txni)

      Required by Better Fps, Chunk Activity Tracker, Does It Tick, and
      Dynamic Lights.


  Cupboard  (someaddon)

      Required by Smooth Chunk Save and Better Fps; also adds off-thread
      entity crash protection.


  Oblivious Core  (Foufakirby)

      Dependency library.



  ---  CANARY  -  NOW INCLUDED  (was previously removed)  ---


  Canary  (AbdElAziz333)

      A Lithium port: mob AI, pathfinding, entity collisions, voxel shapes,
      block-entity ticking and collection tuning. 158 of its mixins apply in
      this stack, covering roughly 80 target classes that no other mod here
      touches. It is the only mod in the bundle optimizing runtime game logic
      rather than startup, memory, chunks or rendering.

      EARLIER REVISIONS REMOVED IT, and that was correct at the time - there
      was no known fix for its ServerCore conflict. There is one now, and it
      is two lines in config/canary.properties (shipped with this bundle):

            mixin.alloc.chunk_ticking=false
            mixin.world.chunk_tickets=false

      The first is the one that mattered. Canary and ServerCore both @Redirect
      the same instruction in ServerChunkCache.tickChunks, and Canary's higher
      priority meant it won and silently dropped ServerCore's cached
      ticking-chunk list. Disabling Canary's redirect costs one ArrayList per
      tick and gives ServerCore's far stronger optimization back.

      To be precise about the old wording: this never disabled ServerCore's
      DYNAMIC system. That runs on ChunkMap, MobCategory and PlayerList, none
      of which Canary touches. What it blocked was cache-ticking-chunks.

      DO NOT add Canary without that config file. Radium and Radon are forks
      of the same base - pick one, never two.


  Krypton  (Steinborn / Forge port)

      Network stack optimization: packet encoding, flush consolidation, and a
      faster per-chunk entity lookup when streaming chunks to players. No
      config, no conflicts with anything else here.

      Most of its value needs a DEDICATED server with real sockets. On an
      integrated singleplayer world the connection is in-memory and the
      compression, encryption and framing work has nothing to attach to.
      Harmless to include; do not expect it to move singleplayer numbers.




===============================================================================

  4.  KEY SETTINGS ALREADY DIALED IN  (inside config/)

===============================================================================



  ---  servercore/config.yml  ---


  disable-spawn-chunks = true

      The biggest single win on a pack with many dimensions.


  prevent-moving-into-unloaded-chunks = false

      Left OFF. When on, it rubber-bands players out of slow-loading chunks
      and can trap or kill them. Only enable it on servers so lag-broken that
      chunk access would otherwise crash them.


  autosave-interval = 12000

      Saves roughly every 10 minutes instead of 5, halving the save spikes.


  SIMULATION_DISTANCE locked at 12 / 12

      Never drops, so entity AI that depends on distance (stalkers and
      similar) keeps working correctly.


  VIEW_DISTANCE locked at 96 / 96

      Deliberately "cancelled out". ServerCore only ever clamps view distance
      DOWN (its constructor acts solely when the current value exceeds max),
      and min == max leaves the dynamic manager no range to move within. The
      result is that ServerCore never touches view distance at all - the
      player's own render distance setting stands.

      If you would rather ServerCore manage it, set max to your actual render
      distance and min to a floor you can live with, e.g. 12 / 7. Do NOT set
      max below your render distance: once it throttles you down, that max is
      the ceiling it can restore to.


  CHUNK_TICK_DISTANCE = 10 down to 4

      Raised from a floor of 2. This gates mob spawning, random block ticks
      and inhabited-time accrual, via ChunkMap.playerIsCloseEnoughForSpawning
      (vanilla hardcodes 128 blocks). At a floor of 2 that becomes 32 blocks
      under load - no vanilla spawns and no crop or ice ticks past your feet.
      4 gives a 64-block floor, which also lines up with Does It Tick?'s
      cutoff so both degrade at the same radius.

      Note this does NOT gate entity ticking; that follows simulation
      distance, which stays pinned at 12.


  MOBCAP_PERCENTAGE minimum = 70

      Keeps spawning healthy during TPS dips.


  Optional tweaks NOT applied (left at tested-clean defaults):

      - xp-merge-fraction = 1   for instant XP merging

      - target-mspt = 45        if you want ServerCore less aggressive on an
                                already-loaded server



  ---  saturn-optimizations.toml  ---


  All four optimizations are ON: memory allocation, GC heap, leak fixes, and
  lock deduplication.

  Note: ModernFix also patches the biome-temperature-cache leak. Both
  @Overwrite Biome.getTemperature at the same priority, so the winner depends
  on mod load order and you get a "method overwrite conflict ... Skipping
  method" line on launch. In practice SATURN wins and ModernFix's copy is
  skipped - the opposite of what earlier revisions of this file said.

  This bundle now settles it explicitly in config/modernfix-mixins.properties:

        mixin.perf.remove_biome_temperature_cache=false

  Saturn's version is the better one anyway - it also nulls the ThreadLocal to
  actually release the cache, where ModernFix's only swaps the methods. No
  performance is lost either way; this just makes it deterministic and removes
  the warning. You can alternatively switch Saturn's biome-temp option off
  to silence it, but it is purely cosmetic.



  ---  entityculling.json  ---


  The whitelist shipped here carries leftover entries from other packs (Create,
  Botania, Alex's Caves, and so on). Those simply will not match anything in a
  pack that lacks those mods, so they are harmless.

  Keep Entity Culling enabled, including on horror packs - it culls by
  occlusion raytrace, not distance, and never touches server-side AI. The
  earlier advice to disable it here was wrong and is retracted; see
  "READ IF MAKING HORROR MODS.txt" section 1.

  You rarely need to whitelist anything. If a specific entity must draw even
  when fully behind terrain, add it here.



  ---  noseenotick-common.toml  AND  does_it_tick-common.toml  ---


  Both ship long entity whitelists left over from other packs (Twilight Forest,
  AoA3, Ice and Fire, Cataclysm, and others). Those entries do not match
  anything in a pack that lacks those mods, so they are harmless.

  If you reuse this on a pack with important long-range, boss or stalker
  entities, whitelist them. The easiest route is by mod ID, in
  does_it_tick-common.toml:

        EntitiesModIDWhiteList = ["your_mod_id"]

  Take the ID from the jar's META-INF/mods.toml - not the filename, and not
  the network channel name, which often differ.

  Do not wait for a freeze to show up in multiplayer. Does It Tick? runs at
  ANY player count, so a stalker beyond 64 blocks is already frozen in
  singleplayer. No See No Tick is the multiplayer-gated one.

  No See No Tick's tick distances in this bundle are set to 262144 (512
  squared) horizontal and 512 vertical. That is deliberate - those same two
  keys also drive its client-side render culling, which ignores the frustum
  and would otherwise hide entities you are looking straight at. Do not lower
  them below your render distance.



  ---  chunky/config.json  ---


  Default Chunky config; world-specific pregeneration tasks were stripped for
  portability. Run a pregen on your target world BEFORE play, for example:

      /chunky radius 1000
      /chunky start

  Ideally do this solo, before inviting others.




===============================================================================

  5.  SUGGESTED JVM FLAGS  (G1GC)

===============================================================================


Not required, but they smooth garbage collection on long sessions:

      -XX:+UseG1GC
      -XX:+ParallelRefProcEnabled
      -XX:MaxGCPauseMillis=200
      -XX:+UnlockExperimentalVMOptions
      -XX:+DisableExplicitGC
      -XX:G1NewSizePercent=30
      -XX:G1MaxNewSizePercent=40
      -XX:G1HeapRegionSize=8M
      -XX:G1ReservePercent=20
      -XX:G1MixedGCCountTarget=4




===============================================================================

  6.  INSTALL ORDER  (target pack)

===============================================================================


  1.  Confirm the target pack is Forge 1.20.1.

  2.  Add the library mods first: Balm, TxniLib, Cupboard, Oblivious Core.

  3.  Add the optimization mods.

  4.  Add Embeddium (and Oculus only if using shaders). Remove any existing
      Rubidium, Magnesium, or OptiFine first; they conflict with Embeddium.

  5.  Canary is now part of the stack, but ONLY together with the shipped
      config/canary.properties. Without it, Canary silently disables
      ServerCore's cached ticking-chunk list. Never run Canary alongside
      Radium or Radon - they are forks of the same base.

  6.  Drop this config/ folder into the pack's config/, overwriting when asked.

  7.  Launch once to let configs settle, then run a Chunky pregen before real
      play.




===============================================================================

  7.  REALISTIC EXPECTATIONS  (integrated / peer-to-peer)

===============================================================================


      Players          Expected TPS
      -------          ------------

      Solo             about 20

      2                15 - 18

      3                15 - 18

      5                12 - 16


A dedicated server (which moves rendering off the server thread) is the only
thing that pushes a heavy multi-dimension pack to a rock-solid 20 with several
players.

20 TPS is the hard cap; nothing makes Minecraft tick faster than that.




===============================================================================

  8.  CREDITS

===============================================================================


  Mod stack - created, curated, and tuned by zebyve.

      The selection of mods, the dialed-in config/ files, and the tuning that
      produced these results are zebyve's work.


  Individual mods - each mod is the work of its original author, credited by
  name in MODS-TO-INSTALL.txt and in section 3 above.

      zebyve did not author the individual mods; all credit for those belongs
      to their respective creators.


===============================================================================
